//! # 框架核心接口定义
//! 
//! 本模块定义了RustCloud框架的核心接口，包括生命周期管理和健康检查接口。

use rustcloud_core::{ServiceResult, ServiceInstance};
use std::collections::HashMap;

/// 框架生命周期管理接口
/// 
/// 定义了框架级别的生命周期管理操作，支持组件的协调启动和停止。
#[async_trait::async_trait]
pub trait FrameworkLifecycle: Send + Sync {
    /// 启动框架
    /// 
    /// 按照依赖顺序启动所有注册的组件，确保依赖关系正确建立。
    async fn start(&self) -> ServiceResult<()>;
    
    /// 停止框架
    /// 
    /// 按照与启动相反的顺序停止所有组件，确保优雅关闭。
    async fn stop(&self) -> ServiceResult<()>;
    
    /// 获取框架状态
    async fn get_state(&self) -> FrameworkState;
    
    /// 健康检查
    /// 
    /// 检查框架及所有组件的健康状态。
    async fn health_check(&self) -> ServiceResult<HealthStatus>;
}

/// 框架状态枚举
#[derive(Debug, Clone, PartialEq)]
pub enum FrameworkState {
    /// 未初始化
    Uninitialized,
    /// 初始化中
    Initializing,
    /// 已启动
    Running,
    /// 停止中
    Stopping,
    /// 已停止
    Stopped,
    /// 错误状态
    Error(String),
}

/// 框架健康状态
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HealthStatus {
    /// 总体状态
    pub status: HealthLevel,
    /// 组件健康状态详情
    pub components: HashMap<String, ComponentHealth>,
    /// 检查时间
    pub timestamp: std::time::SystemTime,
}

/// 健康等级
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HealthLevel {
    /// 健康
    Healthy,
    /// 警告
    Warning,
    /// 不健康
    Unhealthy,
    /// 未知
    Unknown,
}

/// 组件健康状态
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ComponentHealth {
    /// 健康等级
    pub level: HealthLevel,
    /// 状态描述
    pub message: Option<String>,
    /// 详细信息
    pub details: HashMap<String, String>,
}